Sign in mobile users with a self-hosted page #5880
Conversation
susanharper-okta
requested review from
barbaravo-okta,
brentschaus-okta,
emikhasyak-okta,
grahamsmith-okta,
ishan-krishna-okta,
janethu-okta,
madhurishivakumar-okta and
paulwallace-okta
as code owners
This comment was marked as outdated.
This comment was marked as outdated.
|
Netlify Preview URL for the changes: https://preview-5880--reverent-murdock-829d24.netlify.app |
| layout: Guides | ||
| --- | ||
|
|
||
| Add authentication to your mobile app using a self-hosted sign-in page with the Okta Client SDK. |
There was a problem hiding this comment.
| Add authentication to your mobile app using a self-hosted sign-in page with the Okta Client SDK. | |
| Add authentication to your mobile app using a self-hosted sign-in page with the Okta Client SDK for Swift. |
|
|
||
| ## Build the authentication service | ||
|
|
||
| With setup complete, implement the core authentication logic and create a service layer that handles all interactions with the Okta DirectAuth API. |
There was a problem hiding this comment.
| With setup complete, implement the core authentication logic and create a service layer that handles all interactions with the Okta DirectAuth API. | |
| With setup complete, implement the core authentication logic and create a service layer that handles all interactions with the [Okta DirectAuth API](https://okta.github.io/okta-mobile-swift/development/documentation/oktadirectauth/). |
|
|
||
| **State management**: The service maintains the current authentication state (idle, authenticating, authenticated, or error), allowing your UI to respond appropriately. This state-driven approach makes it easy to show loading indicators, error messages, or authenticated content. | ||
|
|
||
| **Security best practices**: All token handling and storage is managed through the service, ensuring that credentials are stored securely in the iOS keychain through `AuthFoundation`. Your UI never directly touches sensitive data. |
There was a problem hiding this comment.
| **Security best practices**: All token handling and storage is managed through the service, ensuring that credentials are stored securely in the iOS keychain through `AuthFoundation`. Your UI never directly touches sensitive data. | |
| **Security best practices**: All token handling and storage is managed through the service, ensuring that credentials are stored securely in the iOS keychain through [`AuthFoundation`](https://okta.github.io/okta-mobile-swift/development/documentation/authfoundation/). Your UI never directly touches sensitive data. |
|
|
||
| **Security best practices**: All token handling and storage is managed through the service, ensuring that credentials are stored securely in the iOS keychain through `AuthFoundation`. Your UI never directly touches sensitive data. | ||
|
|
||
| **Testability**: By defining a protocol (AuthServicing), you can easily create mock implementations for unit testing your views without making actual network calls to Okta. |
There was a problem hiding this comment.
| **Testability**: By defining a protocol (AuthServicing), you can easily create mock implementations for unit testing your views without making actual network calls to Okta. | |
| **Testability**: By defining a protocol (`AuthServicing`), you can easily create mock implementations for unit testing your views without making actual network calls to Okta. |
| // MARK: - Authentication Methods | ||
|
|
||
| func authenticate(username: String, password: String) async throws { | ||
| // 1️⃣ Update state to show authentication is in progress |
There was a problem hiding this comment.
Are we starting to use these number icons now? I don't think we use them anywhere else.
There was a problem hiding this comment.
It took me a minute to realize that the numbers in the code correspond to the numbers that follow. Once I got it, I see that it works well. But it wasn't clear to me at first.
packages/@okta/vuepress-site/docs/guides/sign-users-in-mobile-self-hosted/main/index.md
Show resolved
Hide resolved
packages/@okta/vuepress-site/docs/guides/sign-users-in-mobile-self-hosted/main/index.md
Show resolved
Hide resolved
packages/@okta/vuepress-site/docs/guides/sign-users-in-mobile-self-hosted/main/index.md
Show resolved
Hide resolved
packages/@okta/vuepress-site/docs/guides/sign-users-in-mobile-self-hosted/main/index.md
Show resolved
Hide resolved
packages/@okta/vuepress-site/docs/guides/sign-users-in-mobile-self-hosted/main/index.md
Show resolved
Hide resolved
|
|
||
| If the network request fails or the token is invalid, return `nil` rather than crashing. The calling code can decide how to handle the missing data. | ||
|
|
||
| ### Complete AuthService code |
There was a problem hiding this comment.
Because "complete" can also be a verb, this threw me for a minute. Would it be okay to write it like "Full AuthService code" or "The full AuthService code"?
| // MARK: - Authentication Methods | ||
|
|
||
| func authenticate(username: String, password: String) async throws { | ||
| // 1️⃣ Update state to show authentication is in progress |
There was a problem hiding this comment.
Since this is the full code, and the dev has already (presumably) walked through the "understand" sections, should we drop the numbers from the "full code sample"?
| } | ||
| ``` | ||
|
|
||
| With the `AuthService` complete, you now have a robust authentication layer that handles the sign-in and sign-out flows, token management, and user profile retrieval. This service forms the foundation of your app's security, and because it's protocol-based, it's easy to test and maintain. |
There was a problem hiding this comment.
This content almost gets buried at the end of the sample. What if you put it up under the "Complete code" header, before the full sample?
| ``` | ||
|
|
||
| ## How they work together | ||
|
|
There was a problem hiding this comment.
I understand that this is a good sum-up of the flow, but I wonder if a version of this wouldn't serve better towards the beginning of the guide?
|
|
||
| 1. **Build and run**: Press `Cmd+R` to build and run your app in the simulator. | ||
| 1. **Enter credentials**: Use valid Okta user credentials from your org. | ||
| 1. **Sign in**: Tap **Sign In**. |
There was a problem hiding this comment.
This is a funny one :)
I know that they're running the sim, but presumably they're running it in Xcode so they're clicking it. But they're simulating a tap.
| 1. **Sign in**: Tap **Sign In**. | ||
| 1. **View token**: After successful authentication, your access token appears. | ||
| 1. **Explore features**: | ||
| * Tap **View Profile** to see user information. |
There was a problem hiding this comment.
Same with these. I think that they're clicking, rather than tapping. The simulation runs in the IDE and they're using the pointer with their mouse to click.
Please note: this is by no means a hill I'm prepared to die on haha
packages/@okta/vuepress-site/docs/guides/sign-users-in-mobile-self-hosted/main/index.md
Show resolved
Hide resolved
| **Token expiration**<br> | ||
| Access tokens typically expire after one hour. Use the **Refresh Token** button to get a new one without reauthenticating. | ||
|
|
||
| ## Understand session persistence |
There was a problem hiding this comment.
Should we put this up where we have "Implement the AuthService"? Not sure why this is dropped down below the troubleshooting content.
|
|
||
| The `AuthFoundation` library stores tokens securely in the iOS keychain, which persists across app launches. This creates a seamless experience while maintaining security. | ||
|
|
||
| ## Security considerations |
There was a problem hiding this comment.
Should this be towards the beginning of the doc near the Overview section? Seems important and risks getting lost at the end of a long guide.
|
|
||
| * **Error handling**: Provide clear error messages without exposing sensitive security details. | ||
|
|
||
| ## Beyond username and password |
There was a problem hiding this comment.
Same with this content.
brentschaus-okta
left a comment
brentschaus-okta
left a comment
There was a problem hiding this comment.
Looks good. Some suggested edits and a few questions. Please let me know what you think :)
Acrolinx scoreA minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Successfully checked 3 of 3 documents. Reopen the pull request or push new changes to check again. Depending on the Acrolinx server configuration, the |
|
|
||
| * **Use only HTTPS**: Ensure that all API calls use secure connections. Okta enforces this by default. | ||
|
|
||
| * **Consider adding MFA**: Password-only authentication is less secure than password + MFA. Consider adding support for more factors as your app matures. |
There was a problem hiding this comment.
| * **Consider adding MFA**: Password-only authentication is less secure than password + MFA. Consider adding support for more factors as your app matures. | |
| * **Consider adding MFA**: Password-only authentication is less secure than password + MFA. Consider adding support for more authenticators as your app matures. |
There was a problem hiding this comment.
If this is OIE, I think this should be authenticators instead of factors
grahamsmith-okta
left a comment
grahamsmith-okta
left a comment
There was a problem hiding this comment.
Just a few comments
|
|
||
| * **Use only HTTPS**: Ensure that all API calls use secure connections. Okta enforces this by default. | ||
|
|
||
| * **Consider adding MFA**: Password-only authentication is less secure than password + MFA. Consider adding support for more factors as your app matures. |
There was a problem hiding this comment.
If this is OIE, I think this should be authenticators instead of factors
|
|
||
| ### Understand the AuthService architecture | ||
|
|
||
| The `AuthService` is the heart of our authentication system. It serves as a centralized layer that manages the entire authentication lifecycle, from the initial sign-in flow to session maintenance. By encapsulating all authentication logic in a single service, Okta achieves several important goals: |
There was a problem hiding this comment.
| The `AuthService` is the heart of our authentication system. It serves as a centralized layer that manages the entire authentication lifecycle, from the initial sign-in flow to session maintenance. By encapsulating all authentication logic in a single service, Okta achieves several important goals: | |
| The `AuthService` is the heart of Okta's authentication system. It serves as a centralized layer that manages the entire authentication lifecycle, from the initial sign-in flow to session maintenance. By encapsulating all authentication logic in a single service, Okta achieves several important goals: |
|
|
||
| The `AuthService` is the heart of our authentication system. It serves as a centralized layer that manages the entire authentication lifecycle, from the initial sign-in flow to session maintenance. By encapsulating all authentication logic in a single service, Okta achieves several important goals: | ||
|
|
||
| **Separation of concerns**: The service isolates authentication logic from UI code, making it both easier to test and maintain. Your SwiftUI views don't need to know how direct authentication works, they simply call methods like `authenticate()` or `logout()`. |
There was a problem hiding this comment.
| **Separation of concerns**: The service isolates authentication logic from UI code, making it both easier to test and maintain. Your SwiftUI views don't need to know how direct authentication works, they simply call methods like `authenticate()` or `logout()`. | |
| **Separation of concerns**: The service isolates authentication logic from UI code, making it easier to both test and maintain. Your SwiftUI views don't need to know how direct authentication works, they simply call methods like `authenticate()` or `logout()`. |
| } | ||
| ``` | ||
|
|
||
| This protocol defines the contract for our authentication service, making it easy to test and mock later. |
There was a problem hiding this comment.
| This protocol defines the contract for our authentication service, making it easy to test and mock later. | |
| This protocol defines the contract for the Okta authentication service, making it easy to test and mock later. |
|
|
||
| `ProfileView`: Display user information | ||
|
|
||
| After the user is authenticated, users want to see their profile information. The `ProfileView` performs the following actions: |
There was a problem hiding this comment.
| After the user is authenticated, users want to see their profile information. The `ProfileView` performs the following actions: | |
| After the user is authenticated, they want to see their profile information. The `ProfileView` performs the following actions: |
| ## Handle common issues | ||
|
|
||
| **Invalid credentials**<br> | ||
| If you see an authentication error, verify that: |
There was a problem hiding this comment.
| If you see an authentication error, verify that: | |
| If you see an authentication error, verify the following: |
| * The Resource Owner Password grant type is enabled in your authorization server | ||
|
|
||
| **Configuration errors**<br> | ||
| If the app crashes on launch: |
There was a problem hiding this comment.
| If the app crashes on launch: | |
| If the app crashes on launch, verify the following: |
Acrolinx scoreA minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Successfully checked 3 of 3 documents. Reopen the pull request or push new changes to check again. Depending on the Acrolinx server configuration, the |
Acrolinx scoreA minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Successfully checked 3 of 3 documents. Reopen the pull request or push new changes to check again. Depending on the Acrolinx server configuration, the |
Description:
Netlify
https://preview-5880--reverent-murdock-829d24.netlify.app/docs/guides/sign-users-in-mobile-self-hosted/main/
Resolves: